home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Demo's / Tools&Utilities / Programming / File Dropper 1.1b1 / Read Me - File Dropper < prev   
Encoding:
Text File  |  1993-04-17  |  6.7 KB  |  166 lines  |  [TEXT/KAHL]
  1.                                     File Dropper 1.1ß1
  2.                                     Written by Troy Anderson
  3.  
  4.                     Copyright © 1992-1993, Troy Anderson; All Rights Reserved
  5.  
  6.                                     What Is This Thing?
  7.  
  8. File Dropper is a THINK C library that implements an application that you can drop files or 
  9. folders onto to do batch operations on.  It handles the getting of the AppleEvents if 
  10. running under System 7, the main event loop, and the menus.  You need only write the code 
  11. that acts on the individual files.
  12.                                     
  13.                                     New Features in 1.1ß1
  14.                                     
  15. • Now you can specify if you want the status dialog displayed while you are working on the files,
  16.   wether they were selected with SFGetFile or an AppleEvent.
  17. • There is a progress bar like Finder 7's that you update by specifying how far along you are with
  18.   a percentage (0 - 100).  You can elect to turn this option off, too.
  19.  
  20.     
  21.                                     How Do I Implement My Part?
  22.  
  23. All definitions and prototypes that you need are in the "FD Interface.h" file.  You simply write
  24. the ModuleMain function, and let the library do the rest.
  25.  
  26. The ModuleMain function takes two parameters, a short and a ModuleDataRec.  The short is a 
  27. message that tells you why you were called.  The ModuleDataRec is a record that contains data 
  28. that you may need in order to perform the required task.  It returns a Boolean value.  The
  29. returned value is ignored in all but one case, when you are sent an eValidateFile message.  See
  30. the eValidateFile message description below for details.
  31.  
  32. Be sure that all of the resources in "File Dropper Starter π.rsrc" are included in the resource
  33. file for your project.  It's easiest to make a copy of "File Dropper Starter π.rsrc" and use it.
  34.  
  35. To allow dropping of different types of files/folders/volumes onto your application, change the
  36. 'FREF' resource to include the types of files you can act on.  There are some special types that
  37. correspond to folders, volumes, etc.  For a more indepth discussion of this, see section 9-17 
  38. of Inside Macintosh Volume VI.  See section 9-30 for a list of file types you can use for folders,
  39. floppy disks, the trash, etc.
  40.  
  41. Be sure to change the creator type in the Set Project Type… menu of THINK C, and the creator 
  42. type in the resource file, and to give your application a cool icon.
  43.  
  44.                                     What Is A ModuleDataRec?
  45.  
  46. The ModuleDataRec is defined as follows:
  47.  
  48. typedef struct {
  49.     FSSpec    *theFile;        // a file specification
  50.     long    refcon;            // a reference constant for you to do with what you will
  51.     } ModuleDataRec;
  52.  
  53.                                     What Are The Messages?
  54.                                     
  55. There are 6 possible messages, they are eStartup, eAEInitialize, eSFInitialize, 
  56. eValidateFile, eProcessFile, eDispose, and eQuitting.
  57.  
  58. You get the messages in this order:
  59.  
  60. eStartup
  61.     This tells you that the program just started up.  You get this message exactly once.
  62.     In the ModuleDataRec, theFile and refcon are initialize to NULL and 0 respectively.  You
  63.     are free to use refcon for anything you choose, including allocating a handle and saving
  64.     its value in refcon so you can have additional storage.  Nothing really precludes you from
  65.     having global data hanging around, but someday this thing may evolve into a CODE resource
  66.     interface that will make having globals more difficult. I never touch refcon, so what you
  67.     do with it is up to you.
  68.     
  69.     This is a good place to call the customization routines like SetStatusParams,
  70.     InstallCustomGetFSSpecFunc,    InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc,
  71.     although it's all right to call them from eAEInitialize or eSFInitialize as well.
  72.     
  73. eAEInitialize or eSFInitialize
  74.     This tells you that a file/folder/volume has been selected by the user to be acted upon.
  75.  
  76.     eAEInitialize indicates that the file/folder/volume was "dropped" onto the application or
  77.     sent to it using an 'odoc' AppleEvent.
  78.  
  79.     eSFInitialize indicates that the file (of folder or volume if you've installed a Custom
  80.     GetFSSpec Function using InstallCustomGetFSSpecFunction()) was selected by the user using
  81.     a standard get file dialog.
  82.     
  83.     It is handy to know wether the file was obtained from a "drop" or from a dialog if you have
  84.     options based on keys pressed when "dropped," but not when obtainde from a dialog.
  85.     
  86.     You will receive one of these messages for each batch of files to be processed,
  87.     before you are told to do any processing.
  88.     
  89.     In ModuleDataRec, theFile is meaningless during this message.
  90.  
  91. eValidateFile
  92.     This asks you if the file specified in the theFile parameter of the ModuleDataRec record
  93.     is valid for you to work on.  I.E. should eProcessFile be sent?  Return TRUE if you want
  94.     to process it, otherwise return FALSE.
  95.     
  96. eProcessFile
  97.     This tells you to do your thing.  You get this message for each file in the batch.  The
  98.     ModuleDataRec will contain a pointer to the FSSpec for the file that you are to process
  99.     in the theFile parameter.
  100.  
  101. eDispose
  102.     This tells you that the batch is finished.  This balances out the eAEInitialize or 
  103.     eSFInitialize messages.  It gives you a chance to clean up any data structures you
  104.     set up there.
  105.     
  106.     In ModuleDataRec, theFile is meaningless.
  107.  
  108. eQuitting
  109.     This tells you that the application is about to quit.  If you need to save or flush anything,
  110.     this is the time to do it.
  111.     
  112.     In ModuleDataRec, theFile is meaningless.
  113.  
  114.  
  115. In summary:
  116.  
  117. eStartup
  118.     REPEAT AS LONG AS USER SELECTS THINGS FROM THE GET FILE DIALOG
  119.         eSFInitialize
  120.             REPEAT FOR EACH FILE
  121.                 eValidateFile
  122.                 eProcessFile    (if validation succeeded)
  123.             END REPEAT
  124.         eDispose
  125.     END REPEAT
  126. eQuitting
  127.  
  128. -OR-
  129.  
  130. eStartup
  131.     eAEInitialize
  132.         REPEAT FOR EACH FILE
  133.             eValidateFile
  134.             eProcessFile    (if validation succeeded)
  135.         END REPEAT
  136.     eDispose
  137. eQuitting
  138.  
  139.  
  140.  
  141.                                     About The Guy Who Wrote It
  142.                                     
  143. This was written by me, Troy Anderson, after a comment from a user of Marker that wanted source
  144. so he could do something else with the files that were dropped on the application.  This allows
  145. you to create little utility applications that do fun things.  If you really like this, and you
  146. write software, send me a copy of it.  Thanks.
  147.  
  148. Internet: tla@netcom.com
  149. Compuserve: 70410,1407
  150. America Online: Troy A1
  151. US Mail:    Troy Anderson
  152.             5550 East Roadrunner Road
  153.             Paradise Valley, AZ  85253
  154.  
  155.                                     Legal Stuff
  156.                                     
  157. If you like it, let me know.  If you want to pay for it, send me money.  If there are bugs, tell
  158. me, I may actually fix them.  Every effort has been made to ensure that this software
  159. works as specified, but it has no warranties, expressed or implied, as to its usefulness, 
  160. stability, or functionalty.  Use this software at your own risk. 
  161.  
  162. You may use and distribute applications made with File Dropper at no charge, but you may not
  163. sell them, or collect money for their distribution (normal disk duplication fees excepted).  
  164. Anyone wishing to distribute an application using File Dropper along with any commercial or 
  165. shareware software package may do so only with my express written consent.
  166.